kdam 0.3.0 - Docs.rs

kdam is a console progress bar library for rust. It is port of tqdm library which is written in python. kdam supports all features of tqdm except few. Some features of tqdm can't be ported directly so they are implemented in different way like RowManager which manages multiple progress bars but in tqdm progress bars are automatically managed using nrows. In addition to tqdm existing features kdam also provides extra features such as spinners, charset with fill, gradient colours etc. Since kdam is written in rust its upto 4 times faster than tqdm.

Instantly make your loops show a smart progress meter. Just wrap any iterator with tqdm!(iterator) macro and you're done!

use kdam::tqdm;

fn main() {
    for _ in tqdm!(0..100) {}
}

100%|█████████████████████████████| 100/100 [00:00<00:00, 25854.49it/s]

kdam also supports different animation styles. All available animation styles are:

examples/showcase/animations.rs showcase_animations

kdam also supports rich.progress style bars with customizable columns.

examples/rich.rs showcase_rich_progress_animation

kdam doesn't restrict you to use default progress bar styles. You can create your own progress bar template using bar_format. Here is clone of alive-progress using kdam.

examples/template.rs showcase_alive_progress_template

Using a gradient progress bar can be more appealing than using a plain b/w progress bar sometimes.

examples/coloured/gradient.rs showcase_gradient

Getting Started

Add this to your Cargo.toml file.

[dependencies]
kdam = "0.3.0"

Or add from command line.

$ cargo add kdam

See docs and examples to know how to use it.

Usage

Iterator Based

use kdam::tqdm;

fn main() {
    let chars = ["a", "b", "c", "d"];
    let mut charset = String::new();

    for i in tqdm!(chars.iter()) {
        charset += i;
    }

    eprint!("\n");
    assert_eq!(charset, "abcd");
}

Manual

use kdam::{tqdm, BarExt};

fn main() {
    let mut pb = tqdm!(total = 100);

    for _ in 0..100 {
        pb.update(1);
    }

    eprint!("\n");
}

Another example without a total value. This only shows basic stats.

use kdam::{tqdm, BarExt};

fn main() {
    let mut pb = tqdm!();

    for _ in 0..10000000 {
        pb.update(1);
    }
    pb.refresh();

    eprint!("\n");
}

10000000 [00:03, 2998660.35it/s]

Examples

Description And Additional Stats

Custom information can be displayed and updated dynamically on kdam bars with the desc and postfix.

use kdam::{tqdm, BarExt};

fn main() {
    let mut pb = tqdm!(total = 10);
    pb.set_postfix(format!("str={}, lst={:?}", "h", [1, 2]));
    pb.refresh();

    for i in 0..10 {
        std::thread::sleep(std::time::Duration::from_secs_f32(0.5));
        pb.set_description(format!("GEN {}", i));
        pb.update(1);
    }
    
    eprint!("\n");
}

GEN 4:  50%|█████████▎        | 5/10 [00:02<00:02, 1.95it/s, str=h, lst=[1, 2]]

Nested Progress Bars

kdam supports nested progress bars. For manual control over positioning (e.g. for multi-processing use), you may specify position=n where n=0 for the outermost bar, n=1 for the next, and so on.

use kdam::tqdm;

fn main() {
    for _ in tqdm!(0..4, desc = "1st loop", position = 0) {
        for _ in tqdm!(0..5, desc = "2nd loop", position = 1) {
            for _ in tqdm!(0..50, desc = "3rd loop", position = 2) {
                std::thread::sleep(std::time::Duration::from_secs_f32(0.0001));
            }
        }
    }

    eprint!("{}", "\n".repeat(3));
    println!("completed!");
}

1st loop:  50%|███████▎      | 2/4 [00:08<00:08, 0.25it/s]
2nd loop:  60%|████████▌     | 3/5 [00:02<00:01, 1.25it/s]
3rd loop:   0%|▎               | 0/50 [00:00<00:00, ?it/s]

Writing Messages And Inputs

Since kdam uses a simple printing mechanism to display progress bars, you should not write any message in the terminal using println!() while a progressbar is open.

To write messages in the terminal without any collision with kdam bar display, a .write() method is provided. This message will print at bar output location, which is stderr by default.

use kdam::{tqdm, BarExt};

fn main() {
    let mut pb = tqdm!(total = 10);

    for i in 0..10 {
        std::thread::sleep(std::time::Duration::from_secs_f32(0.1));

        pb.update(1);
        pb.write(format!("Done task {}", i));
    }

    eprint!("\n");
}

Done task 0
Done task 1
Done task 2
Done task 3
Done task 4
Done task 5
Done task 6
Done task 7
Done task 8
Done task 9
100%|███████████████████████████| 10/10 [00:02<00:00, 4.31it/s]

Similarly .input() method can be called to store an user input.

use kdam::{tqdm, BarExt};

fn main() {
    let mut pb = tqdm!(total = 10);

    for i in 0..10 {
        if i == 5 {
            if pb.input("Break Loop [y/n]: ").unwrap().trim() == "y" {
                break;
            }
        }

        pb.update(1);
    }

    eprint!("\n");
}

Break Loop [y/n]: y
 50%|███████████████▎              | 5/10 [00:01<00:01, 3.83it/s]

Terminal Colorization

kdam also provides a text colorization trait for printing colored text in terminal. It can be used as an alternative for existing colored crate. Note that tty detection is not implemented, an alternative is to use atty crate to detect if stream is tty and then use set_colorize function.

use kdam::term::Colorizer;

println!("{}", "hello world!".colorize("bold red"));
println!("{}", "hello world!".colorize("bright white on blue"));

License

Dual Licensed